|
(SST) ShlWAPI.pas Version 1.08 |
|---|---|
| Developer Reference |
| Locates the file name component in a path, if present. |
| Scope |
|---|
| Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas). |
| Syntax | |
|---|---|
 |
PathFindFileName(pszPath : LPCSTR) : LPSTR; |
| Parameters | |
|---|---|
| pszPath [in] | Pointer to a null-terminated, path string, with a length that does not exceed MAX_PATH (= 260) ANSI or Uicode characters (including the terminating ANSI or Unicode null character). |
| Return Values |
|---|
|
If the function succeeds in locating the file name portion of the path string,
it returns a pointer to the first letter of the file name component.
The function returns NIL if the parameter passed to it on call is either
NIL or an empty string.
If the input string consists only of the root portion of a path
(e.g. A:\), it returns a pointer to the beginning of the input string.
|
| Remarks |
|---|
| The function does not verify the existence and/or accessiblity of any portion of the path, nor does it determine if the last component (i.e. that part that comes after the last or second to last backslash) is a file. |
| If the file name has a file extension/suffix, that is considered part of the file name. |
| With the exception of the limit on the length of the input string, this function is essentially identical to the Delphi SDK function ExtractFileName. |
| The function can also handle (and will return the same results) with Unix style (i.e. slash instead of backslash) path delimiters. |
| The function does not remove the last backslash if the input string is terminated by one (see example(s), below). |
| The function may return a pointer to a part of the path that is not the name or entire name, if a name contains characters that are invalid or have a special meaning in DOS/Windows paths (e.g. :, *, ?, etc.). |
| Example |
|---|
| PROCEDURE TForm4.TestShlWAPIPathFindFileName(Sender : TObject); VAR fullpath : STRING; VAR filecomponentp : PChar; VAR newinfoline : STRING; BEGIN fullpath := ''; filecomponentp := NIL; newinfoline := ''; fullpath := 'C:\Hello\Windows\World\WinApplication.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Win.Application.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Win Application.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Folder.With.Periods\WinApplication.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Folder.With.Periods\WinFileNoSuffix'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Folder.With.Periods\FileOrFolderNoSuffix\'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Folder.With.Periods\Invalid:CharInName*.Suffix\'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\Hello\Windows\World\Win Application.exe\'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:\'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'C:'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := '\\UNCSERVER\'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := '\\UNCSERVER\Hello\Windows\World\Win.Application.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := 'D:/Hello/Unix/World/WinApplication.exe'; newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); newinfoline := filecomponentp; Memo1.Lines.Add(newinfoline); fullpath := ''; //Empty string newinfoline := 'PathFindFileName called with: ' + fullpath; Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(PChar(fullpath)); IF ((filecomponentp <> NIL) AND (filecomponentp^ <> #0)) THEN newinfoline := filecomponentp ELSE newinfoline := 'NIL'; Memo1.Lines.Add(newinfoline); fullpath := ''; newinfoline := 'PathFindFileName called with: NIL'; //NIL Memo1.Lines.Add(newinfoline); filecomponentp := PathFindFileName(NIL); IF (filecomponentp <> NIL) THEN newinfoline := filecomponentp ELSE newinfoline := 'NIL'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; |
| The above example produces the following output: |
| PathFindFileName called with: C:\Hello\Windows\World\WinApplication.exe WinApplication.exe PathFindFileName called with: C:\Hello\Windows\World\Win.Application.exe Win.Application.exe PathFindFileName called with: C:\Hello\Windows\World\Win Application.exe Win Application.exe PathFindFileName called with: C:\Hello\Windows\World\Folder.With.Periods\WinApplication.exe WinApplication.exe PathFindFileName called with: C:\Hello\Windows\World\Folder.With.Periods\WinFileNoSuffix WinFileNoSuffix PathFindFileName called with: C:\Hello\Windows\World\Folder.With.Periods\FileOrFolderNoSuffix\ FileOrFolderNoSuffix\ PathFindFileName called with: C:\Hello\Windows\World\Folder.With.Periods\Invalid:CharInName*.Suffix\ CharInName*.Suffix\ PathFindFileName called with: C:\Hello\Windows\World\Win Application.exe\ Win Application.exe\ PathFindFileName called with: C:\ C:\ PathFindFileName called with: C: C: PathFindFileName called with: \\UNCSERVER\ UNCSERVER\ PathFindFileName called with: \\UNCSERVER\Hello\Windows\World\Win.Application.exe Win.Application.exe PathFindFileName called with: D:/Hello/Unix/World/WinApplication.exe WinApplication.exe PathFindFileName called with: NIL PathFindFileName called with: NIL NIL |
| Requirements | |
|---|---|
| Unit: | Declared and imported in (SST)ShlWAPI.pas |
| Library: | (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj |
| Unicode: | Implemented as ANSI (PathFindFileName and PathFindFileNameA) and Unicode (PathFindFileNameW) functions. |
| Min. ShlWAPI.dll version according to MS SDK doc.: | 4.71 |
| Min. ShlWAPI.dll version based on SST research: | 4.71 |
| Min. OS version(s) according to Microsoft SDK doc.: | Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0 |
| Min. OS version(s) according to SST research.: | Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later |
| See Also |
|---|
| PathFindExtension, PathFindNextComponent, PathFindSuffixArray, PathGetArgs |
| Windows APIs: PathFindExtension, PathFindFileName, PathFindNextComponent, PathFindSuffixArray, PathGetArgs |
|
Document/Contents version 1.00 Page/URI last updated on 07.12.2023 |
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 |
Suggestions and comments mail to: webmaster@stoelzelsoftwaretech.com |